------------------------------- Hareng-tool -------------------------------

Version 1.2
10/08/2006


Cette documentation est destinée aux personnes sachant programmer, et plus
spécifiquement, qui ont une connaissance du langage Lua (et éventuellement
C pour mieux comprendre certaines explications de cette documentation).

Pour ceux qui ne connaissent pas Lua, une documentation complète se trouve
sur le site officiel de Lua : http://www.lua.org.


 --------------------------------
| Descriptif rapide de l'API Lua |
 --------------------------------

L'interpréteur Lua a eu droit à quelques ajouts, principalement autour des fonctions
d'extraction et d'insertion (j'ai aussi rajouté les opérations binaires du C qui sont
indisponibles en Lua).

Les fonctions binaires sont les suivantes :
   - andB
   - orB
   - xorB
   - notB
   - shift_l
   - shift_r

Les types de base qui servent pour l'extracteur/insereur :
   - Buffer
   - Fichier
   - Output

Les types en rapport avec l'extracteur/insereur :
   - Pointeur
   - Table_pointeurs
   - Table_ext_ins

Deux fonctions :
   - Ext_ins.extraire
   - Ext_ins.inserer

Tout ceci peut permettre de s'affranchir des restrictions de l'utilisation habituelle
d'une extracteur/inséreur : ici il est possible de construire sa propre table de pointeurs
avec des pointeurs éparpillés dans la rom, d'extraire un script dont les données et les
pointeurs se situent dans des fichiers différents, etc.


 --------------------
| Fonctions binaires |
 --------------------

Les opérateurs utilisés correspondent à ceux du C.

andB(num1, num2)
   Retourne la valeur : num1 & num2

orB(num1, num2)
   Retourne la valeur : num1 & num2

xorB(num1, num2)
   Retourne la valeur : num1 ^ num2

notB(num1, num2)
   Retourne la valeur : num1 ^ num2

shift_l(num, shift)
   Retourne la valeur : num << shift

shift_r(num, shift)
   Retourne la valeur : num >> shift


 ---------------
| Types de base |
 ---------------

-- Buffer --

Le type buffer est un tableau d'unsigned char de longueur variable

Buffer.new()
   Renvoie un nouveau buffer.

buffer:push(num)
   Rajoute la valeur "num" à la fin du buffer.

buffer:clear(i)
   Vide le buffer.

buffer:size()
   Renvoie le nombre d'éléments contenus dans le buffer.

buffer:index(i [, val])
   Si l'argument "val" est absent, renvoie le ième élément du buffer.
   Si l'argument "val" est présent, remplace le ième élément par
      la variable "val".
   A noter : le premier indice, comme sur un tableau C est 0.


-- Fichier --

Le type fichier est semblable au type file de Lua mais je lui ai rajouté
quelques possibilités.

Fichier.new()
   Renvoie une nouvelle variable de type Fichier.

fichier:open(nom_fichier, options)
   Ouvre le fichier "nom_fichier" selon les options données via la variable
      "options"?.
   Cette fonction s'utilise comme la fonction fopen en C.

fichier:close()
   Ferme le fichier.

fichier:put(val)
   Ecrit la variable "val" à la position courante.

fichier:get()
   Renvoie l'octet qui se trouve à la position courante.

fichier:seek(adresse, origine)
   Déplace la position courante à la position "adresse", par rapport à l'origine spécifiée.
   L'origine est donnée par les constantes suivantes :
      - SEEK_SET : origine du fichier
      - SEEK_CUR : position actuelle
      - SEEK_END : fin du fichier
   Cette fonction s'utilise de la même manière que la fonction fseek en C.

fichier:tell()
   Renvoie la position actuelle

fichier:read(buffer, n)
   Lit n octets à partir de la position courrante et stocke le tour dans la variable buffer.

fichier:write(buffer [, n])
   Ecrit n octets dans le fichier à la position courrante.
   Si n n'est pas donné, le buffer sera écrit en entier.

fichier:load_text(buffer)
   Cette fonction charge un fichier texte dans le buffer donné.
   Le fichier doit s'ouvrir avec les options "rb", le chargement se fait indépendament
   de l'encodage des retours à la ligne (elle les détecte seule).


-- Output --

Ce type sert essentiellement pour l'extracteur/inséreur.
Il permet de créer une variable où l'on peut faire des affichages de nombres et de chaines
simplement, mais on peut spécifier où se fait l'affichage lors de la construction de l'objet.
Par exemple ce type sert pour l'extracteur : on extrait le texte vers un Output, mais ça peut
être un Buffer ou un Fichier. De même, on peut insérer un texte vers un Buffer ou directement
dans un endroit précis de la rom.

Output.new([type [, nom_fichier, option]])
   Cette fonction renvoie un Output du type donné. Les types sont les suivants :
      - "Buffer"
      - "Fichier"
   Si aucun argument n'est donné, la sortie utilisée est la sortie standard (sortier sur
   la console).
   Les arguments nom_fichier et option servent dans le cas du tpe "Fichier" : ce sont les
   option d'ouverture du fichier (de la même manière que fichier:open()).

output:print(arg [, type])
   Ecrit dans l'Output l'argument arg, qui peut être un nombre, une chaine ou un buffer.
   Dans le cas d'un nombre, le type vient préciser s'il s'agit d'un int ou d'un char. Il faut
   respectivement préciser le type "int" et le type "char".

output:get_fichier()
   Renvoie une variable de type fichier qui permet dans le cas d'un Output vers un fichier
   de manipuler le fichier de sortie.

output:get_buffer()
   Renvoie une variable de type buffer qui permet dans le cas d'un Output vers un buffer
   de manipuler le buffer de sortie.


 ------------------------------
| Types d'extraction/insertion |
 ------------------------------

**************
-- Pointeur --
**************

Ce type représente un pointeur que l'on peut utiliser afin de créer sa table de pointeur (voir
type suivant).
Un pointeur contient 3 informations : son numéro, sa valeur et sa taille.
Le numéro sert à écrire la balise de pointeur dans le texte (<PT0043> par exemple), de façon à
savoir de quel pointeur il s'agit.
La valeur est la valeur du pointeur à proprement parler (donc l'adresse sur laquelle il pointe).
Sa taille correspond au nombre d'octets sur lequel il est stocké (2, 3, 4).

Pointeur.new()
   Renvoie un nouveau pointeur

pointeur:numero([i])
   Si i est absent, la fonction renvoie le numéro du pointeur.
   Sinon, i est le nouveau numéro.

pointeur:valeur([i])
   Si i est absent, la fonction renvoie la valeur du pointeur.
   Sinon, i est la nouvelle valeur.

pointeur:taille([i])
   Si i est absent, la fonction renvoie le numéro du pointeur.
   Sinon, i est la nouvelle taille.

pointeur:ecrire(fichier)
   Ecrit le pointeur dans le fichier donné.
   Par exemple, on a le pointeur suivant :
      - Numéro : 34
      - Valeur : 0x1234
      - Taille : 3
   Il sera écrit comme cela dans la rom :
         00 12 34
   C'est à dire que la fonction écrit n octets, où n correspond à la taille du pointeur.
   De plus il faut bien noter la façon dont est écrit le pointeur (de l'octet de poids
   fort vers l'octet de poids faible).


*********************
-- Table_pointeurs --
*********************

Ce type consitue un tableau variable de pointeurs qui peut être lu et modifié. Il sert
pour l'extracteur et à l'inséreur (qui va modifier la table de pointeurs en lui ajoutant
des entrées).

Table_pointeurs.new([taille])
   Renvoie une nouvelle table de pointeur.
   Si la taille est spécifiée, elle sera la taille de tous les pointeurs.

table_pointeurs:charger(fichier, debut, nb, taille)
   Charge la table de pointeur à partir du fichier donné.
   Les pointeurs sont chargés à partir de l'adresse "debut", "nb" pointeurs sont chargés
   suivant la taille spécifiée.
   La façon dont sont lus les pointeurs est identique à la logique de la fonction
   pointeur:ecrire(). Petit exemple :
      On a un pointeur stocké comme cela dans la rom : 12 00 34.
      Si on charge un pointeur de taille 3, sa valeur sera : 0x120034.

table_pointeurs:vider()
   Vide la table de pointeur.

table_pointeurs:ajouter(pointeur)
   Ajoute le pointeur donné.

table_pointeurs:retirer(i)
   Retire le pointeur qui se trouve à l'index i.

table_pointeurs:calculer(formule [, debut [, fin]])
   Effectue l'opération donnée par la formule sur un certain nombre de pointeur :
    - Si les bornes debut et fin ne sont pas données, le calcul se fera sur toute la table.
    - Si les bornes sont toutes deux données, le calcul se fera sur les pointeurs dont les
      indices sont entre ces bornes (bornes incluses).
    - Si seule la première borne est donnée, le calcul se fera uniquement sur le pointeur
      d'index spécifié.

table_pointeurs:inverser([debut [, fin]])
   Inverse une série de pointeurs avec la même logique que la fonction de calcul.

table_pointeurs:index(i [, pointeur])
   Lire/écrit un pointeur.
   - Renvoie le pointeur d'index i si le second argument est absent.
   - Sinon, remplace le pointeur d'index i par le pointeur spécifié.
   L'index commence à 0.

table_pointeurs:fixer_taille_pt()
   Fixe la taille de tous les pointeurs de la table. Tous les pointeurs contenus sont
   ajustés en conséquence.

table_pointeurs:nb_pt()
   Renvoie le nombre de pointeurs contenus dans la table.

table_pointeurs:taille_pt()
   Renvoie la taille des pointeurs de la table.

table_pointeurs:trier_num()
   Trie les pointeurs selon leur numéro.

table_pointeurs:trier_val()
   Trie les pointeurs selon leur valeur.

table_pointeurs:afficher()
   Affiche la table sur la sortie standard.


*******************
-- Table_ext_ins --
*******************

Ce type permet de charger une table destinée à l'extracteur/inséreur.

Table_ext_ins.new()
   Renvoie une nouvelle variable du type Table_ext_ins.

Table_ext_ins:ouvrir(nom_table)
   Charge la table nom_table (nom du fichier).

Table_ext_ins:fermer()
   Ferme la table.

Table_ext_ins:afficher()
   Affiche la table sur la sortie standard.


 ---------------------------------------------
| Fonctions d'extraction/insertion génériques |
 ---------------------------------------------

Dans ce qu'il suit, vous trouverez deux noms : texte_binaire et texte.
J'appelle "texte_binaire" le texte sous la forme où on peut le trouver dans
une rom alors que "texte" correspond au dump du texte.

Ces fonctions sont assez génériques, et simples d'usage. Toutefois, c'est
à l'utilisateur de savoir utiliser les résultats des fonctions en les insérant
lui même dans la rom en programmant un peu.

Ext_ins.extraire(texte_binaire, table, texte, pointeurs)
   Types :
      - texte_binaire : Buffer
      - table : Table_ext_ins
      - texte : Output
      - pointeurs : Table_pointeurs

   Extrait le texte_binaire en lisant la table données ainsi que la table de pointeurs
   donnée.
   Il est important de noter que les pointeurs pointent vers des adresses DANS le buffer
   du texte.
   C'est à dire que si vous avez une phrase qui se trouve à l'index x dans votre buffer,
   le pointeur correspondant devra avoir la valeur x en question.

   Il est donc possible de modifier la sortie du dump en jouant avec l'Output donné.


Ext_ins.inserer(texte, table, texte_binaire, pointeurs)
   Types :
      - texte : Buffer
      - table : Table_ext_ins
      - texte_binaire : Output
      - pointeurs : Table_pointeurs

   Insère le texte donné en lisant la table. Le texte binaire créé est stocké dans la variable
   texte_binaire. Les pointeurs sont écrits dans la table de pointeur.

